# HistoryPanel 可视化

上一章 [HistoryPanel（历史数据面板）](2.5.%20historypanel.md) 介绍了如何把多标的、多指标的历史数据对齐到同一块面板。本章说明如何**直接用面板出图**：与「先 `to_share_frame` 再手写 matplotlib」相比，**`HistoryPanel.plot()`** 根据当前 `htypes` 自动组合 K 线、成交量、MACD、折线等视图，使探索数据时的上下文与策略研究阶段保持一致。

---

## `hp.plot()`：推荐的统一入口

项目中将 **`HistoryPanel.plot()`** 作为**唯一推荐的制图入口**（旧有接口若仍存在，语义上也应委托到同一套流水线）。你只需保证面板中非空且包含绘图所需的列（例如完整 OHLC 才能出蜡烛图），其余图表类型由内部根据 `htypes` 自动判定。

常用参数含义如下（完整签名见 [HistoryPanel API](../api/HistoryPanel.rst)）：

| 参数 | 作用概要 |
| --- | --- |
| `shares` | 要绘制的标的子集；默认使用面板内全部标的。 |
| `layout` | 多标的布局：`'overlay'`（同一坐标系叠加）、`'stack'`（分组纵向分面）、`'auto'`（例如 2 只标的倾向 overlay，更多则 stack）。 |
| `interactive` | `False` 使用 **matplotlib** 静态图；`True` 使用 **Plotly** 交互图（缩放、平移、悬停等）。 |
| `highlight` | 高亮极值点等，例如 `'max'` / `'min'` 或传入配置字典。 |
| `plotly_backend_app` | 仅在 `interactive=True` 时有效：`'auto'`（优先 FigureWidget，失败则回退 HTML 包装）、`'FigureWidget'`、`'html'`。 |

**说明**：当请求的标的数量较多时，实现可能会**限制实际绘制的标的数量**并发出警告，以避免单图过载；具体以当前版本行为为准。多标的布局的细微调整与历史修复说明见 [RELEASE_HISTORY](../RELEASE_HISTORY.md) 中 2.2.x 相关条目。

## 静态图与交互图

- **`interactive=False`（默认）**：依赖 **matplotlib**，适合脚本批量出图、生成静态文件；不强制安装 Plotly。
- **`interactive=True`**：依赖 **plotly**；在 Jupyter 中若 **`anywidget` 与 `ipywidgets`** 可用，通常可得到 **FigureWidget**，表头与坐标轴交互更完整；否则可能回退为 **HTML 包装** 形式，仍具备基本交互，但与 Widget 路径在体验上略有差异。

极简示例（需本地已有 OHLCV 或等价列；仅作形式演示）：

```python
import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000300.SH',
    rows=120,
    as_data_frame=False,
)
fig = hp.plot()                      # 静态
# fig2 = hp.plot(interactive=True)  # 交互（需安装 plotly 等）
```

当主图为蜡烛图时，静态图会在时间轴**最后一根 K 线**上显示 OHLC 摘要；交互图默认一致，点击某根 K 线后摘要会更新为该根（面向用户的摘要文案为英文）。无完整 OHLC 时不会出现该摘要区。

## 布局与多标的

- **`overlay`**：适合对比少数标的（如两只股票）在同一价格尺度下的走势（具体是否共享 y 轴以当前实现为准）。
- **`stack`**：每个标的（或每组）单独占一行子图，适合标的较多、避免挤在同一坐标系。
- **`auto`**：在标的数量较少时倾向叠加，较多时倾向分面，减少手动试错。

若某版本后布局语义有调整，**以对应版本的 [RELEASE_HISTORY](../RELEASE_HISTORY.md) 说明为准**。

## 依赖与安装提示

- **静态图**：一般需要 **matplotlib**（与 qteasy 常用环境一致）。
- **交互图**：需要 **plotly**；完整 Notebook 交互体验建议同时安装 **ipywidgets** 与 **anywidget**。可选依赖的版本范围以项目 **`pyproject.toml`** 或安装文档为准，本文不逐条罗列版本号。

底层渲染模块名与扩展点仅供开发者阅读源码时使用；用户文档不展开文件级实现细节。

## 小结

- 数据准备仍通过 **`get_history_data`** 等与 [上一章](2.5.%20historypanel.md) 一致；制图统一走 **`hp.plot()`**。
- **`interactive`** 与 **`layout`** 是日常最常被改动的两个开关；进阶参数见 API 文档。
- 行为变更与可视化相关修复请查阅 **[RELEASE_HISTORY](../RELEASE_HISTORY.md)**；动手练习可配合教程 **[使用 HistoryPanel 操作和分析历史数据](../tutorials/2.5-historypanel-data-analysis.md)**。